Summary

This PR restores Bun macro support for the models.dev data fetching functionality, as requested in issue #6. The implementation adds the macro directive while maintaining backward compatibility through automatic fallback.

Key Changes

1. Restored macro directive in src/provider/models.ts:

   import { data } from "./models-macro" with { type: "macro" }

2. Added comprehensive documentation in docs/MACRO_SUPPORT.md explaining:

   • How macros work in this codebase
   • Limitations and restrictions
   • Fallback behavior
   • Alternative approaches considered

How It Works

• Development mode: Macros execute at bundle-time for faster startup
• Production mode: Graceful fallback to runtime fetching when installed from npm
• No breaking changes: Existing functionality preserved

Limitations

Due to Bun's security model, macros cannot execute from node_modules. This is a fundamental restriction documented in the official Bun macro documentation:

"For security reasons, macros cannot be run from node_modules."

This means:

• ✅ Macros work when running from source (development)
• ❌ Macros don't work when installed globally (bun install -g)
• ✅ Runtime fallback works automatically in production

Testing

The macro has been tested and verified to work in development mode:

# Test macro functionality
bun run experiments/test-macro.ts
# Output: Successfully fetches ~600KB JSON from models.dev

The existing test suite continues to pass, confirming backward compatibility.

Alternative Approaches Investigated

1. Pre-bundling with bun build:

   • Attempted to inline macro results at build time
   • Result: Async macros with network fetching caused bundler to hang
   • Likely a current limitation in Bun's macro implementation

2. Bundling cached JSON:

   • Would work but adds ~600KB to package size
   • Current runtime fetch + cache approach is more efficient

Conclusion

This implementation provides the best of both worlds:

• Development performance: Macro optimization when running from source
• Production reliability: Automatic runtime fetching when installed as package
• Zero configuration: Fallback is transparent to users

While macros cannot work in globally-installed packages due to Bun's security model, restoring the macro directive enables development-time optimizations and keeps the door open for future improvements if Bun adds support for pre-compiled/bundled packages.

Fixes #6

🤖 Generated with Claude Code